Ficha técnica

Alcances necesarios

El token para consumir esta API debe generarse utilizando el Authorization Code.

El alcance openid es obligatorio. Permite consultar el perfil del usuario BTG con acceso a la cuenta.

Es necesario incluir el siguiente alcance:

Alcance	Descripción
brn:btg:empresas:banking:collections	Permite la consulta y gestión de pagos, lotes y cuentas

Entorno de sandbox

Esta API está disponible únicamente en el sandbox (api.sandbox.empresas.btgpactual.com), un entorno de pruebas para que usted construya y valide su integración antes de operar con datos reales.

• Nada de lo que usted hace aquí mueve dinero real.
• Todo lo que usted crea puede consultarse después mediante el id devuelto.
• Los datos de prueba pueden reiniciarse periódicamente.
• Toda creación o modificación debe enviar el header X-Idempotency-Key. Repetir la misma clave devuelve el mismo resultado, sin duplicar la operación.

Qué puede hacer

• Pagos y comprobantes: pague por Pix, TED, boleto, DARF y otros medios, y obtenga el comprobante de cada pago concluido.
• Lotes: reúna varios pagos y dispárelos todos de una sola vez.
• Cuentas, saldo y extracto: consulte las cuentas de la empresa, el saldo disponible y los movimientos.

El status de cada recurso lo define la plataforma y usted nunca lo informa.

Recorrido de un pago

1. Consulte sus cuentas y el saldo. Identifique la cuenta de origen y confirme que hay saldo disponible.
2. Inicie el pago. Informe el medio (por ejemplo, Pix o TED), el valor y los datos del beneficiario. El pago nace con un id.
3. Espere la aprobación, si es necesaria. Según las reglas de la empresa, el pago queda en pending_approval hasta ser aprobado.
4. Siga el resultado. Consulte el pago por el id hasta que llegue a un estado final: settled (concluido), failed (rechazado) o canceled (cancelado por usted).
5. Obtenga el comprobante. Para pagos concluidos, consulte el comprobante.
6. Verifique en el extracto. El pago aparece como débito en los movimientos de la cuenta.

Mientras el pago todavía no se haya concluido, usted puede cancelarlo. Después de settled, failed o canceled, ya no acepta nuevas modificaciones, excepto la devolución de un pago ya concluido.

Recorrido de un lote

1. Abra un lote. Comienza vacío y tiene plazo y capacidad máxima de pagos.
2. Agregue pagos al lote. Al iniciar cada pago, informe el batchRef del lote. Los pagos solo se disparan cuando el lote se procesa.
3. Procese el lote. Todos los pagos se disparan de una sola vez. Si el lote exige aprobación, una única aprobación libera todos los elementos.
4. Siga el avance. El lote muestra cuántos pagos ya se concluyeron y, al final, queda totalmente concluido o parcialmente fallido.
5. Abandone, si desiste. Un lote aún no procesado puede descartarse sin disparar ningún pago.

Cómo simular el avance de un pago

En el sandbox no hay un banco real que confirme las operaciones. Para simular lo que ocurriría en producción, use POST /{companyId}/banking/primitives/_sandbox/advance, informando el resourceId del pago y el event deseado:

event	Resultado en el pago
settle	Pago concluido (settled)
fail	Rechazado por el medio de pago (failed)
require_approval	Esperando aprobación (pending_approval)
approve	Aprobado (approved)
revert	Devuelto después de concluido

Eventos de webhook

Próximamente

Los webhooks de esta API todavía no están disponibles. Por ahora, siga el avance de los pagos y lotes consultándolos por el id.

Cuando se habiliten, usted podrá recibir notificaciones automáticas sobre los cambios de estado, sin necesidad de consultar repetidamente. Esta página se actualizará con la lista de eventos y sus payloads.